# Deploying Java Extensions

Note: Java Extensions are also referred to as Optional Packages.

This section covers the following topics:

- Overview
- Specifying Java Extensions in the Applet
- Java Extensions Installation
- Detailed Instructions
- How It Works
- Security
- Known Limitations

Java applets may use various Java Extensions to provide certain functions to users. Deploying Java Extensions dynamically with Java applets in Java Plug-in has been a challenge to developers, especially those with thousands of machines in an intranet/Internet environment.

Java Extensions Installation enables various Java Extensions (e.g., JavaHelp, Java3D ...) to be deployed and installed easily along with Java applets in the Java 2 Runtime Environment. This document outlines the basic steps for deploying Installed Java Extensions in Java Plug-in. For details about how Java Extensions works, please see the Java Extensions Mechanism documentation in Java 2.

## Overview

To use Java Extensions Installation in Java Plug-in, information about the extensions must be specified in three places:

1. MANIFEST of the applet's JAR files
   If the applet requires Java Extensions Installation, the applet MUST define the list of Java Extensions Installation it requires in the MANIFEST and specify the URLs from which to download the extensions.

2. MANIFEST of the Java Extension Jar files to be installed (i.e., JAR files that will be downloaded to the `\lib\ext` directory)
   The purpose is to make known the extension name, version, and vendor info within the extension JAR file itself. Therefore, Java Plug-in will be able to compare the extension name, version, and vendor info of all the installed extensions (i.e., inside `lib/ext`) to the extension the applet requests; and Java Plug-in will then be able to determine if the extensions need to be installed/upgraded.

3. MANIFEST of the Java Extension Installation's JAR file
   This is the JAR file which the applets refer to with the Implementation-URL attribute in the MANIFEST. The purpose is to indicate the extension installation type, so the installation will be triggered properly.

## Specifying Java Extensions in the Applet

To deploy Java Extensions with applets, the applet must be packaged as a JAR file. The MANIFEST file of the applet must contain proper information about the Java Extensions to be installed, according to the Optional Package Versioning. For example,

    Extension-List: RectangleArea RectanglePerimeter
    RectangleArea-Extension-Name: com.mycompany.RectangleArea
    RectangleArea-Specification-Version: 1.2
    RectangleArea-Implementation-Version: 1.2
    RectangleArea-Implementation-Vendor-Id: com.mycompany
    RectangleArea-Implementation-URL: http://mycompany.com/RectangleArea.jar
    RectanglePerimeter-Extension-Name: com.mycompany.RectanglePerimeter
    RectanglePerimeter-Specification-Version: 1.2
    RectanglePerimeter-Implementation-Version: 1.2
    RectanglePerimeter-Implementation-Vendor-Id: com.mycompany
    RectanglePerimeter-Implementation-URL: http://mycompany.com/RectanglePerimeter.jar

In this example, two extensions are deployed with the applet—`RectangleArea` and `RectanglePerimeter`. If they have not been installed or if updates are needed, the proper versions will be downloaded from the `Implementation-URL` specifications. Notice that an `Implementation-URL` must point to a JAR file which is the Java Extensions Installation.

## Note on Proper JAR Extension Identification: Note that Java Plug-in checks four `MANIFEST.MF` attributes of an installed extension `JAR` file: `Extension-Name` `Specification-Version` `Implementation-Version` `Implementation-Vendor-Id` `Extension-Name` and `Implementation-Vendor-Id` must match exactly the values specified in the applet `JAR` `MANIFEST.MF` file. See Optional Package Versioning for how Java Plug-in evaluates the version attributes of an installed extension to decide if a newer extension needs to be downloaded. ### Sun-Supported `Specification-Version` and `Implemenation-Version` Formats `Specification-Version` and `Implementation-Version` follow these rules for Sun products, and third-party products must follow the same rules for Java Plug-in to make reliable decisions about whether an extension is up-to-date or not: The `Specification-Version` string will be of the form: `n1.n2[.n3]` where`n1`, `n2`, and `n3` are integers, `n1.n2` is the major version number, and optional `n3` is the minor version number (also referred to as the maintenance version number). The `Implementation-Version` will be of the same form initially but may: append with a preceding underscore("`_`") `n4n5` to indicate a patch version number (also referred to as the update version number) or append with a hyphen ("`-`") a milestone name (`ea` , `alpha`, `beta`, `rc` ...), which may also include a trailing integer number (`ea1`, `beta2`, `rc1` ...). Both patch version number and milestone name may not be used together in the `Implemenation-Version` string. The general form is as follows: `n1.n2[.n3][_<patch_number>|-<milestone_name>]` Integers (`n1`,`n2`, `n3` ...), letters, dots, hyphens, and underscores , may be used in the version format as described above; no other characters ("`*`", "`+`" ...) are allowed. Note that the `Specification-Version` and `Implementation-Version` numbers are in theory independent, though in practice they are often in sync with each other. Examples: `Specification-Version` examples: `1.3`, `1.4` `Implementation-Version` examples: `1.3.1`, `1.4.0_02`, `1.4.0-beta3` While these are the rules, it is always a good idea when using a third-party extension `JAR` to examine its `MANIFEST.MF` file to see what actual values are in it. If it does not follow these rules, you may need to change your applet `JAR` `MANIFEST.MF` accordingly or alter the extension `JAR`.

## Java Extensions Installation

Three types of Java Extensions Installation are supported in Java Plug-in:

1. Raw Java Extensions
   Java Extensions consist of several JAR files. In the applet's MANIFEST file, these raw Java Extensions are specified through the `Implementation-URL`. During installation, these Java Extensions JAR files will be downloaded and verified, and copied into the Java 2 Runtime `lib/ext` directory.

2. Java installer
   Java Extensions are installed through a Java installer. The Java installer must be bundled as a JAR file, and the resulting JAR file must be specified as `Implementation-URL` in the applet's MANIFEST file. During installation, the JAR file will be downloaded and verified, and the `main-class` of the Java installer inside the JAR file will be executed to start the installer. It is the job of the Java installer to copy the Java Extensions inside the installer into the right location of the Java 2 Runtime (i.e., `lib/ext`).

3. Native installer
   Java Extensions are installed through a native installer. The native installer must be bundled as a JAR file, and the resulting JAR file must be specified as `Implementation-URL` in the applet's MANIFEST file. During installation, the JAR file will be downloaded and verified, and the native installer will be started. It is the job of the native installer to copy the Java Extensions inside the installer into the right location of the Java 2 Runtime (i.e., `lib/ext`).

To ensure the Java Extensions Installations are downloaded and installed properly, they must be bundled as JAR files and be specified as Implementation-URL in the applet's MANIFEST. Each Java Extension itself must be bundled as a JAR files and contain proper versioning information in its own MANIFEST file according to Optional Package Versioning. For example,

1. Raw Java Extensions:

       Extension-Name: javax.help
       Specification-Vendor: Sun Microsystems, Inc
       Specification-Version: 1.4
       Implementation-Vendor-Id: com.sun
       Implementation-Vendor: Sun Microsystems, Inc
       Implementation-Version: 1.4.0_01

   In this case, it will be recognized as a raw Java Extension, and will be copied into the `lib/ext` directory directly.

2. Java Installer:

       Extension-Name: javax.help
       Specification-Vendor: Sun Microsystems, Inc
       Specification-Version: 1.4
       Implementation-Vendor-Id: com.sun
       Implementation-Vendor: Sun Microsystems, Inc
       Implementation-Version: 1.4.0-beta2
       Main-Class: com.sun.javahelp.installer

   In this case, because `Main-Class` is present in the MANIFEST, it will be treated as Java Installer, and `Main-class` will be invoked. It is the job of the Java Installer to copy the Java Extensions into the proper `lib/ext` directory. However, each Java Extension being copied into the `lib/ext` directory must contain proper versioning information as well. For example,

       Extension-Name: javax.help
       Specification-Vendor: Sun Microsystems, Inc
       Specification-Version: 1.4
       Implementation-Vendor-Id: com.sun
       Implementation-Vendor: Sun Microsystems, Inc
       Implementation-Version: 1.4.0-beta2

   This ensures the versioning information of the extensions can be determined by looking in the MANIFEST file of all the JAR files in the `lib/ext` directory.

3. Native Installer:

       Extension-Name: javax.help
       Specification-Vendor: Sun Microsystems, Inc
       Specification-Version: 1.4
       Implementation-Vendor-Id: com.sun
       Implementation-Vendor: Sun Microsystems, Inc
       Implementation-Version: 1.4.0-rc1
       Extension-Installation: installer.exe

   In this case, because `Extension-Installation` is present in the MANIFEST, it will be treated as a native Installer; and the installer itself will be launched. It is the job of the native Installer to copy the Java Extensions into the proper `lib/ext` directory. However, similar to the Java installer case, each Java Extension being copied into the `lib/ext` directory must contain proper versioning information as well. For example,

       Extension-Name: javax.help
       Specification-Vendor: Sun Microsystems, Inc
       Specification-Version: 1.4
       Implementation-Vendor-Id: com.sun
       Implementation-Vendor: Sun Microsystems, Inc
       Implementation-Version: 1.4.0-rc1

   This ensures the versioning information of the extensions can be determined by looking in the MANIFEST file of all the JAR files in the `lib/ext` directory.

## Detailed Instructions

To deploy optional packages with Java applets using the Java Plug-in, follow these steps:

### I. Make the optional package installer JAR file.

> A. Obtain the optional package installer.The Java Plug-in supports three types of installers—Java, Native, and Raw. Be sure to use the correct manifest attribute for the install type

> > Java: `Main-Class`
> > Native: `Extension-Installation`
> > Raw: No manifest attribute

> B. Make the manifest file for the optional package. Here is an example of the optional package Java Advanced Imaging API (`jai_win.jar`) manifest which uses a native installer (`jai-1_1_1-lib-win-jre.exe`). The reason it is recognized as a native installer is because the manifest attribute `Extension-Installation` is used.

> > `Manifest-Version: 1.0
> > Extension-Name: javax.media.jai
> > Extension-Installation: jai-1_1_1-lib-win-jre.exe
> > Specification-Version: 1.1
> > Specification-Vendor: Sun Microsystems. Inc
> > Implementation-Version: 1.1.1
> > Implementation-Vendor: Sun Microsystems, Inc
> > Implementation-Vendor-Id: com.sun`

> C. JAR up the the installer, together with the optional package manifest file, to make the optional package installation JAR file. Be sure to include the .jar extension in the jar file name. Also, depending on the optional package and the type of installation, you may have to include the optional package JAR file(s) in the optional package installation JAR file or stage the optional package JAR file(s) on your web server. Both the optional package installation and the optional package themselves must be bundled as JAR files and contain proper versioning information.

> > `jar cmfv manifest-addition jar-file.jar input-file(s)`

> D. Sign the JAR file.
> You have to obtain an RSA certificate from a certificate authority (Thawte, VeriSign) to be able to sign your JAR file. Below are some tools and commands to used to sign a JAR file. They are not inclusive.
> See How to Sign Applets Using RSA Certificates in the Plug-in document and other related documents for more information on this topic.
> Use `keytool` to generate an RSA `keypair` and your `keystore`:

> > `keytool -genkey -keyalg rsa -alias MyCert -validity 360`

> Use `keytool` to import the certificate into your `keystore`:

> > `keytool -import -file <path>/mycerts/my_veri.p12`

> Use `jarsigner` to sign your JAR file:

> > `jarsigner InstallMyOptPkg.jar MyCert`

> Use `jarsigner` to verify that the JAR file was signed properly:

> > `jarsigner -verify -verbose -certs InstallMyOptPkg.jar`

> E. Put the resulting JAR file (and any other needed JAR files) on your web server so it can be downloaded by users. The URL is specified in the manifest attribute `<extension>-Implementation-URL` in the test applet's manifest file.

### II. Make the applet JAR file and HTML file.

> A. Create the applet that uses the features of the optional package.
> B. Create a manifest file for the applet. Below is an example of a manifest file of an applet declaring its dependency on the optional package Java Advanced Imaging API.

> > `Extension-List: jai
> > jai-Extension-Name: javax.media.jai
> > jai-Specification-Version: 1.1
> > jai-Implementation-Version: 1.1.1
> > jai-Implementation-Vendor-Id: com.sun
> > jai-Implementation-URL: http://myserver.com/jai_win.jar`

> Some optional packages come packaged in different JAR files for different operating systems. If you want your applet to work on the different OS's you can use the `$(os-name)$` construction in the `Implementation-URL` manifest attribute. The `$(os-name)$` will translate to the target OS (i.e. SunOS, Windows-NT) that the applet is being run on.

> > `optpkg-Implementation-URL: http://.../optpkg-$(os-name)$.jar`

> C. JAR up the `*.class` files (and any other supporting files) that the applet uses together with the applet's manifest file. Be sure to include the .jar extension in the jar file name.

> > `jar cmfv manifest-addition jar-file.jar input-file(s)`

> D. Create the HTML page for the applet. Put the name of the above JAR file in the `ARCHIVE` parameter. See Using `OBJECT`, `EMBED` and `APPLET` Tags in Java Plug-in for more information about the required format.

> > `OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
> > width="200" height="200" align="baseline"
> > codebase="http://java.sun.com/products/plugin/1.4/jinstall-14-win32.cab#Version=1,4,0,0">
> > <PARAM NAME="code" VALUE="myapplet.class">
> > <PARAM NAME ="archive" VALUE = "myapplet.jar">
> > <PARAM NAME="type" VALUE="application/x-java-applet;version=1.4">
> > <PARAM NAME="scriptable" VALUE="false">
> > <COMMENT>
> > <EMBED type="application/x-java-applet;version=1.4" width="200"
> > height="200" align="baseline" code="myapplet.class" archive="myapplet.jar"
> > pluginspage="http://java.sun.com/products/plugin/1.4/plugin-install.html">
> > <NOEMBED>
> > </COMMENT>
> > Optional Package Deployment Using Java Plug-in
> > </NOEMBED></EMBED>
> > </OBJECT>`

> E. Use the resulting HTML page to load your applet.
> When you run the applet the Java Plug-in will display a Java Security Warning (if the optional package is not already installed) informing you that the applet requires the installation of optional package `name` from `http://someserver.com/some.jar`. If you grant the installation of the optional package the installer will install the JAR files in the `<jre>\lib\ext` directory. Once the installation is complete your applet will run.

## How It Works

When the applet is deployed with Java Extensions, the Java Extensions information stored in the applet's MANIFEST file will be examined. The extension update algorithm is based on the one described in Optional Package Versioning. If an update is required, the Java Extensions Installation will be downloaded and verified to ensure that the extension is correctly signed. If it is valid, the Plug-in will pop-up a security dialog that provides three options:

1. Grant always: If selected, the extensions installation JAR will be granted "AllPermission". Any signed applet or signed extension that was signed using the same certificate will be trusted automatically in the future, and no security dialog will pop up when this certificate is encountered again. This decision can be changed from the Java Plug-in Control Panel.
2. Grant this session: If selected, the extensions installation will be granted "AllPermission". Any signed applet or signed extension that was signed using the same certificate will be trusted automatically within the same browser session.
3. Deny: If selected, the extensions installation is cancelled.

Once the user selects the options from the security dialog, the extensions installation will be executed in the corresponding security context. The applet will not be started until the extensions are properly installed.

## Security

Because Java Extensions are downloaded and installed into the Java 2 Runtime `lib/ext` directory, each Java Extensions Installation must be signed. Once the Java Extensions are installed, it will have the proper permissions that are granted to Java Extensions through the policy file.

## Known Limitations

- If the Java Extensions Installation is not signed properly, Java Plug-in will fail silently.
- For Java Extensions Installation, please ensure newer versions of the Java Extensions contains at least the same set of the JAR file names as the older versions. Otherwise, installing newer Java Extensions may not overwrite all the older Java Extensions, and there will be a mix of different versions of Java Extensions in the same Java Runtime. The results will be unpredictable.
- If the applet consists of several JAR files, only one of them is required to have the extensions versioning information if Java Extensions installation is used. We recommend putting the versioning information in the first JAR specified in the `archive/cache_archive` attribute to speed up the extensions download.
- If the Java Extensions consists of several JAR files and is installed through Java/native installer, only one of the JAR files is required to have the extensions versioning information. However, for raw extensions installation, each JAR files must contain the proper extensions versioning information.
- If Java Installer is used, make sure the program does not exit the `Main-class` until the installation is done. In some cases, Java Installer may create an AWT window and switch control to a different thread and return immediately from the `Main-class`. Returning control from the `Main-class` will force the applets to be loaded and started immediately, even if the Java Installer is still in the process of installation. This will cause the applet to fail to load because the extension is not installed yet.